package org.marketlive.entity;

/*
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
*/

import java.io.Serializable;

/**
 * Represents a unique identifier for an <code>IEntity</code>.  Corresponds to the concept of a
 * primary key in a relational database.
 */
public interface IPrimaryKey extends Serializable {

    /**
     * Returns the type of entity for which this primary key can be used.
     *
     * @return the type of entity for which this key can be used
     * @see IEntity#getEntityType()
     */
    String getEntityType();

    /**
     * Returns a string representation of this <code>IPrimaryKey</code>.
     * The returned string can be used to generate an equivalent IPrimaryKey object with
     * {@link IEntityHome#getPk(String)} so that for any non-null entity:
     *
     * <pre>
     * IPrimaryKey pk = entity.getPk();
     * pk.equals( entity.getEntityHome().getPk(pk.getAsString());
     * </pre>
     *
     * The returned string must be URL-safe; that is, it must not require encoding.
     *
     * @return a string representation of this <code>IPrimaryKey</code>
     */
    String getAsString();

    /**
     * Returns true if the given object is equal to this <code>IPrimaryKey</code>.
     * Must be implemented such that, for <code>IPrimaryKey</code>s pk1 and pk2:
     * <ul>
     *   <li>if pk1.equals(pk2) then pk2.equals(pk1), and</li>
     *   <li>pk1 and pk2 represent the same record in the underlying persistent store.</li>
     * </ul>
     *
     * @param other the object to compare for equality
     * @return true if the above conditions are met, false otherwise
     */
    boolean equals(Object other);

    /**
     * Returns the hash code of this <code>IPrimaryKey</code>.
     * For efficient caching, all implementations must implement a suitable
     * hashCode algorithm.
     *
     * @return the hashCode of this <code>IPrimaryKey</code>
     */
    int hashCode();

}
